<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>awk</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_000_096">&nbsp;</a>NAME</h4><blockquote>
awk - pattern scanning and processing language
</blockquote><h4><a name = "tag_000_000_097">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

awk <b>[</b>-F <i>ERE</i><b>][</b>-v <i>assignment</i><b>]</b> ... <i>program </i><b>[</b><i>argument</i> ...<b>]</b>

awk <b>[</b>-F <i>ERE</i><b>] </b>-v <i>progfile</i><b>]</b> ... <b>[</b>-v <i>assignment</i><b>]</b> ...<b>[</b><i>argument</i> ...<b>]</b>
</code>
</pre>
</blockquote><h4><a name = "tag_000_000_098">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>awk</i>
utility executes programs written in the
<i>awk</i>
programming language, which is specialised for textual data manipulation.
An
<i>awk</i>
program is a sequence of patterns
and corresponding actions.
When input is read that matches a pattern,
the action associated with that pattern
will be carried out.
<p>
Input is interpreted as a sequence of records.
By default, a record is a line, but this can be changed by using the
<b>RS</b>
built-in variable.
Each record of input is matched in turn
against each pattern in the program.
For each pattern matched, the associated
action will be executed.
<p>
The
<i>awk</i>
utility interprets each input
record as a sequence of fields where, by
default, a field is a string of
non-blank
characters.
This default white-space field delimiter
can be changed by using the
<b>FS</b>
built-in variable or the
<b>-F</b>&nbsp;<i>ERE</i>.
The
<i>awk</i>
utility denotes the first field in a record
$1,
the second
$2,
and so on.
The symbol
$0
refers to the entire record;
setting any other field will cause the reevaluation of
$0.
Assigning to
$0
will reset the values of all other fields and the
<b>NF</b>
built-in variable.
</blockquote><h4><a name = "tag_000_000_099">&nbsp;</a>OPTIONS</h4><blockquote>
The
<i>awk</i>
utility supports the <b>XBD</b> specification, <a href="../xbd/utilconv.html#usg"><b>Utility Syntax Guidelines</b>&nbsp;</a> .
<p>
The following options are supported:
<dl compact>

<dt><b>-F&nbsp;</b><i>ERE</i>
<dd>
Define the input field separator to be the extended regular expression
<i>ERE</i>,
before any input is read; see
<xref href=awkre><a href="#tag_000_000_108_004">
Regular Expressions
</a></xref>.

<dt><b>-f&nbsp;</b><i>progfile</i>
<dd>
Specifies the pathname of the file
<i>progfile</i>
containing an
<i>awk</i>
program.
If multiple instances of this option are specified,
the concatenation of the files specified as
<i>progfile</i>
in the order specified will be the
<i>awk</i>
program.
The
<i>awk</i>
program can alternatively be specified in the
command line as a single argument.

<dt><b>-v&nbsp;</b><i>assignment</i>
<dd>
The
<i>assignment</i>
argument must be in the same form as an
<i>assignment</i>
operand.
The specified variable assignment will occur prior to executing the
<i>awk</i>
program, including the actions associated with
<b>BEGIN</b>
patterns (if any).
Multiple occurrences of this option can be specified.

</dl>
</blockquote><h4><a name = "tag_000_000_100">&nbsp;</a>OPERANDS</h4><blockquote>
The following operands are supported:
<dl compact>

<dt><i>program</i><dd>
If no
<b>-f</b>
option is specified, the first operand to
<i>awk</i>
will be the text of the
<i>awk</i>
program.
The application will supply the
<i>program</i>
operand as a single argument to
<i>awk</i>.
If the text does not end in a
newline
character,
<i>awk</i>
will interpret the text as if it did.


<dt><i>argument</i><dd>
Either of the following two types of
<i>argument</i>
can be intermixed:
<dl compact>

<dt><i>file</i><dd>A pathname of a file that
contains the input to be read, which is matched against the set of
patterns in the program.
If no
<i>file</i>
operands are specified,
or if a
<i>file</i>
operand is "-", the standard input will be used.

<dt><i>assignment</i><dd>
An operand that begins with an underscore or alphabetic character from
the portable character set (see the table in
the <b>XBD</b> specification, <a href="../xbd/charset.html#tag_001_001"><b>Portable Character Set</b>&nbsp;</a> ),
followed by a sequence of underscores, digits and alphabetics from the
portable character set, followed by the
"="
character will specify a variable assignment rather than a pathname.
The characters before the
"="
represent the name of an
<i>awk</i>
variable;
if that name is an
<i>awk</i>
reserved word (see
<xref href=awkgram><a href="#tag_000_000_108_016">
Grammar
</a></xref>)
the behaviour is undefined.
The characters following the equal sign will be interpreted as if
they appeared in the
<i>awk</i>
program preceded and followed by a double-quote
(")
character, as a
<b>STRING</b>
token (see
<xref href=awkgram><a href="#tag_000_000_108_016">
Grammar
</a></xref>),
except that if the last character is an unescaped backslash,
it will be interpreted as a literal backslash rather than as
the first character of the sequence
\".
The variable will be assigned the value of that
<b>STRING</b>
token.
If that value is considered a
<i>numeric string</i>
(see
<xref href=awkexpr><a href="#tag_000_000_108_002">
Expressions in awk
</a></xref>),
the variable will also be assigned its numeric value.
Each such variable assignment will occur just prior to
the processing of the following
<i>file</i>,
if any.
Thus, an assignment before the first
<i>file</i>
argument will be executed after the
<b>BEGIN</b>
actions (if any),
while an assignment after the last
<i>file</i>
argument
will occur before the
<b>END</b>
actions (if any).
If there are no
<i>file</i>
arguments, assignments will be executed before processing the standard input.

</dl>
<p>
</dl>
</blockquote><h4><a name = "tag_000_000_101">&nbsp;</a>STDIN</h4><blockquote>
The standard input will be used only if no
<i>file</i>
operands are specified,
or if a
<i>file</i>
operand is "-".
See the INPUT FILES section.
</blockquote><h4><a name = "tag_000_000_102">&nbsp;</a>INPUT FILES</h4><blockquote>
Input files to the
<i>awk</i>
program from any of the following sources:
<ul>
<p>
<li>
any
<i>file</i>
operands or their equivalents,
achieved by modifying the
<i>awk</i>
variables
<b>ARGV</b>
and
<b>ARGC</b>
<p>
<li>
standard input in the absence of any
<i>file</i>
operands
<p>
<li>
arguments to the
<b>getline</b>
function
<p>
</ul>
<p>
must be text files.
Whether the variable
<b>RS</b>
is set to a value other than a
newline character
or not, for these files,
implementations support
records terminated with the
specified separator up to
{LINE_MAX}
bytes and may support longer records.
<p>
If
<b>-f</b>&nbsp;<i>progfile</i>
is specified,
the files named by each of the
<i>progfile</i>
option-arguments must be text files containing an
<i>awk</i>
program.
</blockquote><h4><a name = "tag_000_000_103">&nbsp;</a>ENVIRONMENT VARIABLES</h4><blockquote>
The following environment variables affect the execution of
<i>awk</i>:
<dl compact>

<dt><i>LANG</i><dd>Provide a default value for the internationalisation variables
that are unset or null.
If
<i>LANG</i>
is unset or null, the corresponding value from the
implementation-dependent default locale will be used.
If any of the internationalisation variables contains an invalid setting, the
utility will behave as if none of the variables had been defined.

<dt><i>LC_ALL</i><dd>
If set to a non-empty string value,
override the values of all the other internationalisation variables.

<dt><i>LC_COLLATE</i><dd>
Determine the locale for the
behaviour of ranges, equivalence classes
and multi-character collating elements
within regular expressions
and in comparisons of string values.

<dt><i>LC_CTYPE</i><dd>
Determine the
locale for the interpretation of sequences of bytes of text data as
characters (for example, single-
versus multi-byte characters in arguments and input files),
the behaviour of character classes within regular expressions,
the identification of characters as letters,
and the mapping of upper- and lower-case characters for the
<b>toupper</b>
and
<b>tolower</b>
functions.

<dt><i>LC_MESSAGES</i><dd>
Determine the locale that should be used to affect
the format and contents of diagnostic
messages written to standard error.

<dt><i>LC_NUMERIC</i><dd>
Determine the radix
character used when interpreting numeric input,
performing conversions between numeric and
string values and formatting numeric output.
Regardless of locale, the period
character (the decimal-point character of the POSIX locale)
is the decimal-point character recognised in processing
<i>awk</i>
programs (including assignments in command-line arguments).

<dt><i>NLSPATH</i><dd>
Determine the location of message catalogues
for the processing of
<i>LC_MESSAGES .
</i>
<dt><i>PATH</i><dd>Determine the search path when looking
for commands executed by
<i>system</i>(<i>expr</i>),
or input and output pipes.
See
the <b>XBD</b> specification, <a href="../xbd/envvar.html"><b>Environment Variables</b>&nbsp;</a> .

</dl>
<p>
In addition, all environment variables will be visible via the
<i>awk</i>
variable
<b>ENVIRON</b>.
</blockquote><h4><a name = "tag_000_000_104">&nbsp;</a>ASYNCHRONOUS EVENTS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_000_000_105">&nbsp;</a>STDOUT</h4><blockquote>
The nature of the output files depends on the
<i>awk</i>
program.
</blockquote><h4><a name = "tag_000_000_106">&nbsp;</a>STDERR</h4><blockquote>
Used only for diagnostic messages.
</blockquote><h4><a name = "tag_000_000_107">&nbsp;</a>OUTPUT FILES</h4><blockquote>
The nature of the output files depends on the
<i>awk</i>
program.
</blockquote><h4><a name = "tag_000_000_108">&nbsp;</a>EXTENDED DESCRIPTION</h4><blockquote>
<h5><a name = "tag_000_000_108_001">&nbsp;</a>Overall Program Structure</h5>
An
<i>awk</i>
program is composed of
pairs of the form:
<pre>
<code>
<i>pattern</i> { <i>action</i> }
</code>
</pre>
Either the pattern or the action (including the enclosing
brace characters) can be omitted.
<p>
A missing pattern will match any
record of input, and a
missing action will be equivalent to an action that writes
the matched record of input to standard output.
<p>
Execution of the
<i>awk</i>
program starts by first executing the actions associated with all
<b>BEGIN</b>
patterns in the order they occur in the program.
Then each
<i>file</i>
operand (or standard input if no files were specified)
will be processed in turn by
reading data from the file until
a record separator is seen
(a newline character
by default),
splitting the current record into fields using the current value of
<b>FS</b>
according to the rules in
<xref href=awkre><a href="#tag_000_000_108_004">
Regular Expressions
</a></xref>,
evaluating each pattern in the
program in the order of occurrence,
and executing the action associated with each
pattern that matches the current record.
The action for a matching pattern will be executed before
evaluating subsequent patterns.
Last, the actions associated with all
<b>END</b>
patterns will be executed in the order they occur in the program.
<h5><a name = "tag_000_000_108_002">&nbsp;</a>Expressions in awk</h5>
<xref type="5" name="awkexpr"></xref>
Expressions
describe computations used in
<i>patterns</i>
and
<i>actions.</i>
In the following table,
valid expression operations are given in groups
from highest precedence first to lowest precedence last,
with equal-precedence operators grouped between horizontal lines.
In expression evaluation,
where the grammar is formally ambiguous,
higher precedence operators will be evaluated
before lower precedence operators.
In this table
<i>expr</i>,
<i>expr1</i>,
<i>expr2</i>
and
<i>expr3</i>
represent any expression,
while
<i>lvalue</i>
represents any entity that can be assigned to (that is, on the left side
of an assignment operator).
The precise syntax of expressions is given in
<xref href=awkgram><a href="#tag_000_000_108_016">
Grammar
</a></xref>.
<pre>
<table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Syntax</b>
<th align=center><b>Name</b>
<th align=center><b>Type of Result</b>
<th align=center><b>Associativity</b>
<tr valign=top><td align=left>( <i>expr</i> )
<td align=left>Grouping
<td align=left>type of <i>expr</i>
<td align=left>n/a
<tr valign=top><td align=left>$<i>expr</i>
<td align=left>Field reference
<td align=left>string
<td align=left>n/a
<tr valign=top><td align=left>++ <i>lvalue</i>
<td align=left>Pre-increment
<td align=left>numeric
<td align=left>n/a
<tr valign=top><td align=left>-- <i>lvalue</i>
<td align=left>Pre-decrement
<td align=left>numeric
<td align=left>n/a
<tr valign=top><td align=left><i>lvalue</i> ++
<td align=left>Post-increment
<td align=left>numeric
<td align=left>n/a
<tr valign=top><td align=left><i>lvalue</i> --
<td align=left>Post-decrement
<td align=left>numeric
<td align=left>n/a
<tr valign=top><td align=left><i>expr</i>^<i>expr</i>
<td align=left>Exponentiation
<td align=left>numeric
<td align=left>right
<tr valign=top><td align=left>! <i>expr</i>
<td align=left>Logical not
<td align=left>numeric
<td align=left>n/a
<tr valign=top><td align=left>+ <i>expr</i>
<td align=left>Unary plus
<td align=left>numeric
<td align=left>n/a
<tr valign=top><td align=left>- <i>expr</i>
<td align=left>Unary minus
<td align=left>numeric
<td align=left>n/a
<tr valign=top><td align=left><i>expr</i> * <i>expr</i>
<td align=left>Multiplication
<td align=left>numeric
<td align=left>left
<tr valign=top><td align=left><i>expr</i> / <i>expr</i>
<td align=left>Division
<td align=left>numeric
<td align=left>left
<tr valign=top><td align=left><i>expr</i> % <i>expr</i>
<td align=left>Modulus
<td align=left>numeric
<td align=left>left
<tr valign=top><td align=left><i>expr</i> + <i>expr</i>
<td align=left>Addition
<td align=left>numeric
<td align=left>left
<tr valign=top><td align=left><i>expr</i> - <i>expr</i>
<td align=left>Subtraction
<td align=left>numeric
<td align=left>left
<tr valign=top><td align=left><i>expr</i> <i>expr</i>
<td align=left>String concatenation
<td align=left>string
<td align=left>left
<tr valign=top><td align=left><i>expr</i> &lt; <i>expr</i>
<td align=left>Less than
<td align=left>numeric
<td align=left>none
<tr valign=top><td align=left><i>expr</i> &lt;= <i>expr</i>
<td align=left>Less than or equal to
<td align=left>numeric
<td align=left>none
<tr valign=top><td align=left><i>expr</i> != <i>expr</i>
<td align=left>Not equal to
<td align=left>numeric
<td align=left>none
<tr valign=top><td align=left><i>expr</i> == <i>expr</i>
<td align=left>Equal to
<td align=left>numeric
<td align=left>none
<tr valign=top><td align=left><i>expr</i> &gt; <i>expr</i>
<td align=left>Greater than
<td align=left>numeric
<td align=left>none
<tr valign=top><td align=left><i>expr</i> &gt;= <i>expr</i>
<td align=left>Greater than or equal to
<td align=left>numeric
<td align=left>none
<tr valign=top><td align=left><i>expr</i> ~ <i>expr</i>
<td align=left>ERE match
<td align=left>numeric
<td align=left>none
<tr valign=top><td align=left><i>expr</i> !~ <i>expr</i>
<td align=left>ERE non-match
<td align=left>numeric
<td align=left>none
<tr valign=top><td align=left><i>expr</i> in array
<td align=left>Array membership
<td align=left>numeric
<td align=left>left
<tr valign=top><td align=left>( <i>index</i> ) in <i>array</i>
<td align=left>Multi-dimension array membership
<td align=left>numeric
<td align=left>left
<tr valign=top><td align=left><i>expr</i> &amp;&amp; <i>expr</i>
<td align=left>Logical AND
<td align=left>numeric
<td align=left>left
<tr valign=top><td align=left><i>expr</i> || <i>expr</i>
<td align=left>Logical OR
<td align=left>numeric
<td align=left>left
<tr valign=top><td align=left><i>expr1</i> ? <i>expr2</i> : <i>expr3</i>
<td align=left>Conditional expression
<td align=left>type of selected <i>expr2</i> or <i>expr3</i>
<td align=left>right
<tr valign=top><td align=left><i>lvalue</i> ^= <i>expr</i>
<td align=left>Exponentiation assignment
<td align=left>numeric
<td align=left>right
<tr valign=top><td align=left><i>lvalue</i> %= <i>expr</i>
<td align=left>Modulus assignment
<td align=left>numeric
<td align=left>right
<tr valign=top><td align=left><i>lvalue</i> *= <i>expr</i>
<td align=left>Multiplication assignment
<td align=left>numeric
<td align=left>right
<tr valign=top><td align=left><i>lvalue</i> /= <i>expr</i>
<td align=left>Division assignment
<td align=left>numeric
<td align=left>right
<tr valign=top><td align=left><i>lvalue</i> += <i>expr</i>
<td align=left>Addition assignment
<td align=left>numeric
<td align=left>right
<tr valign=top><td align=left><i>lvalue</i> -= <i>expr</i>
<td align=left>Subtraction assignment
<td align=left>numeric
<td align=left>right
<tr valign=top><td align=left><i>lvalue</i> = <i>expr</i>
<td align=left>Assignment
<td align=left>type of <i>expr</i>
<td align=left>right
</table>
</pre>
<h6 align=center><xref table="Expressions in Decreasing Precedence in <I>awk</i>"></xref>Table: Expressions in Decreasing Precedence in <i>awk</i></h6>
<xref type="7" name="awkprec"></xref>
<hr size=2 noshade>
<p>
Each expression has either a string value, a numeric value or both.
Except as stated for specific contexts,
the value of an expression will be implicitly converted to the type
needed for the context in which it is used.
A string value will be converted to a numeric value by the equivalent of the
following calls to functions defined by the ISO&nbsp;C standard:
<pre>
<code>
setlocale(LC_NUMERIC, "");
<i>numeric_value</i> = atof(<i>string_value</i>);
</code>
</pre>
A numeric value that is exactly equal to the value of an integer
will be converted to a string by the equivalent of a
call to the
<b>sprintf</b>
function (see
<xref href=awkstr><a href="#tag_000_000_108_013">
String Functions
</a></xref>)
with the string
%d
as the
<i>fmt</i>
argument and the numeric value being converted as the first and only
<i>expr</i>
argument.
Any other numeric value will be converted to a string by the equivalent of a
call to the
<b>sprintf</b>
function with the value of the variable
<b>CONVFMT</b>
as the
<i>fmt</i>
argument and the numeric value being converted as the first and only
<i>expr</i>
argument.
The result of the conversion is unspecified if the value of
<b>CONVFMT</b>
is not a floating-point format specification.
This specification specifies no explicit conversions between numbers
and strings.
An application can force an expression to be treated as a
number by adding zero to it, or can force it to be treated
as a string by concatenating the null string
("")
to it.
<p>
A string value will be considered to be a
<i>numeric string</i>
in the following case:
<ol>
<p>
<li>
Any leading and trailing
blank characters
will be ignored.
<p>
<li>
If the first unignored character is a
"+" or "-", it will be ignored.
<p>
<li>
If the remaining unignored characters would be lexically recognised as a
<b>NUMBER</b>
token (as described by the lexical conventions in
<xref href=awkgram><a href="#tag_000_000_108_016">
Grammar
</a></xref>),
the string will be considered a
<i>numeric string .</i>
<p>
</ol>
<p>
If a "-" character is ignored in the above steps, the numeric
value of the
<i>numeric string</i>
will be the negation of the numeric value of the recognised
<b>NUMBER</b>
token.
Otherwise the numeric value of the
<i>numeric string</i>
will be the numeric value of the recognised
<b>NUMBER</b>
token.
Whether or not a string is a
<i>numeric string</i>
will be relevant only in contexts where that term is used in this section.
<p>
When an expression is used in a Boolean context,
if it has a numeric value, a value of zero is treated as false and
any other value is treated as true.
Otherwise, a string value of the null string is treated as false and
any other value is treated as true.
A Boolean context is one of the following:
<ul>
<p>
<li>
the first subexpression of a conditional expression
<p>
<li>
an expression operated on by logical NOT, logical AND or logical OR
<p>
<li>
the second expression of a
<b>for</b>
statement
<p>
<li>
the expression of an
<b>if</b>
statement
<p>
<li>
the expression of the
<b>while</b>
clause in either a
<b>while</b>
or
<b>do...while</b>
statement
<p>
<li>
an expression used as a pattern (as in Overall Program Structure).
<p>
</ul>
<p>
All arithmetic will follow the semantics of floating-point arithmetic
as specified by the ISO&nbsp;C standard.
<p>
The value of the expression:
<pre>
<code>
<i>expr1</i> ^ <i>expr2</i>
</code>
</pre>
will be equivalent to the value returned by the ISO&nbsp;C standard
function call:
<pre>
<code>
pow(<i>expr1</i>, <i>expr2</i>)
</code>
</pre>
<p>
The expression:
<pre>
<code>
<i>lvalue</i> ^= <i>expr</i>
</code>
</pre>
will be equivalent to the ISO&nbsp;C standard expression:
<pre>
<code>
<i>lvalue</i> = pow(<i>lvalue</i>, <i>expr</i>)
</code>
</pre>
except that
<i>lvalue</i>
will be evaluated only once.
The value of the expression:
<pre>
<code>
<i>expr1</i> % <i>expr2</i>
</code>
</pre>
will be equivalent to the value returned by the ISO&nbsp;C standard function call:
<pre>
<code>
fmod(<i>expr1</i>, <i>expr2</i>)
</code>
</pre>
The expression:
<pre>
<code>
<i>lvalue</i> %= <i>expr</i>
</code>
</pre>
will be equivalent to the ISO&nbsp;C standard expression:
<pre>
<code>
<i>lvalue</i> = fmod(<i>lvalue</i>, <i>expr</i>)
</code>
</pre>
except that
<i>lvalue</i>
will be evaluated only once.
<p>
Variables and fields will be set by the assignment statement:
<pre>
<code>
<i>lvalue</i> = <i>expression</i>
</code>
</pre>
and the type of
<i>expression</i>
will determine the resulting variable type.
The assignment includes the arithmetic assignments
(<b>+=</b>, <b>-=</b>, <b>*=</b>, <b>/=</b>, <b>%=</b>, <b>^=</b>,
<b>++</b>, <b>--</b>) all of
which produce a numeric result.
The left-hand side of an assignment
and the target of increment and decrement operators can be one of
a variable, an array with index or a field selector.
<p>
The
<i>awk</i>
language supplies arrays that are used for storing numbers or strings.
Arrays need not be declared.
They are initially empty,
and their sizes will change dynamically.
The subscripts,
or element identifiers,
are strings, providing a type of associative array capability.
An array name followed by a subscript within square brackets can
be used as an
<i>lvalue</i>
and thus as an expression, as described in the grammar (see
<xref href=awkgram><a href="#tag_000_000_108_016">
Grammar
</a></xref>).
Unsubscripted array names can be used in only the following contexts:
<ul>
<p>
<li>
a parameter in a function definition or function call
<p>
<li>
the
<b>NAME</b>
token following any use of the keyword
<b>in</b>
as specified in the grammar (see
<xref href=awkgram><a href="#tag_000_000_108_016">
Grammar
</a></xref>);
if the name used in this context is not an array name, the behaviour
is undefined.
<p>
</ul>
<p>
A valid array
<i>index</i>
consists of one or more comma-separated expressions,
similar to the way in which multi-dimensional arrays are indexed in
some programming languages.
Because
<i>awk</i>
arrays are really one dimensional,
such a comma-separated list
will be converted to a single string
by concatenating the string values of the separate expressions,
each separated from the other by the value of the
<b>SUBSEP</b>
variable.
Thus, the following two index operations will be equivalent:
<pre>
<code>
<i>var</i><b>[</b><i>expr1</i>, <i>expr2</i>, ... <i>exprn</i><b>]
</b><i>var</i><b>[</b><i>expr1</i> SUBSEP <i>expr2</i> SUBSEP ... SUBSEP <i>exprn</i><b>]</b>
</code>
</pre>
<p>
A multi-dimensioned
<i>index</i>
used with the
<b>in</b>
operator must be parenthesised.
The
<b>in</b>
operator,
which tests for the existence of a particular array element,
will not cause that element to exist.
Any other reference to a non-existent array element will automatically
create it.
<p>
Comparisons (with the "&lt;", "&lt;=", "!=", "==", "&gt;" and "&gt;=" operators)
will be made numerically if both operands are numeric or if one
is numeric and the other has a string value that is a numeric string.
Otherwise, operands will be converted to strings as required
and a string comparison will be made
using the locale-specific collation sequence.
The value of the comparison expression will be
1
if the relation is true, or
0
if the relation is false.
<h5><a name = "tag_000_000_108_003">&nbsp;</a>Variables and Special Variables</h5>
Variables can be used in an
<i>awk</i>
program by referencing them.
With the exception of function parameters (see
<xref href=awkuser><a href="#tag_000_000_108_015">
User-defined Functions
</a></xref>),
they are not explicitly declared.
Uninitialised scalar variables and array elements have both
a numeric value of zero and
a string value of the empty string.
<p>
Field variables are designated by a "$"
followed by a number or numerical expression.
The effect of the field number
<i>expression</i>
evaluating to anything other than a non-negative integer
is unspecified;
uninitialised variables or string values need not be converted to
numeric values in this context.
New field variables can be created by assigning a value to them.
References to non-existent fields (that is, fields after
<b>$NF</b>),
will produce the null string.
However, assigning to a non-existent field
(for example, $(NF +2)
= 5)
will increase the value of
<b>NF</b>,
create any intervening fields with the null string as their values
and cause the value of
$0
to be recomputed, with the fields being separated by the value of
<b>OFS</b>.
Each field variable will have a string value when created.
If the string,
with any occurrence of the decimal-point character from the
current locale changed to a
period character,
would be considered a
<i>numeric string</i>
(see
<xref href=awkexpr><a href="#tag_000_000_108_002">
Expressions in awk
</a></xref>),
the field variable will also have the numeric value of the
<i>numeric string .</i>
<p>
Implementations support the following other special variables
that are set by
<i>awk</i>:
<dl compact>

<dt><b>ARGC</b><dd>The number of elements in the
<b>ARGV</b>
array.

<dt><b>ARGV</b><dd>An array of command line arguments, excluding options and
the <i>program</i> argument, numbered from zero to
ARGC-1.

The arguments in
<b>ARGV</b>
can be modified or added to;
<b>ARGC</b>
can be altered.
As each input file ends,
<i>awk</i>
will treat the next non-null element of
<b>ARGV</b>,
up to the current value of
ARGC-1,
inclusive,
as the name of the next input file.
Thus,
setting an element of
<b>ARGV</b>
to null means that it will not be treated as an
input file.
The name "-" indicates the standard input.
If an argument matches the format of an
<i>assignment</i>
operand,
this argument
will be treated as an assignment rather than a
<i>file</i>
argument.

<dt><b>CONVFMT</b><dd>The
<b>printf</b>
format for converting numbers to strings (except for output statements,
where
<b>OFMT</b>
is used);
%.6g
by default.

<dt><b>ENVIRON</b><dd>The variable
<b>ENVIRON</b>
is an array representing the value of the environment,
as described in the <b>XSH</b> specification
under the
<i>exec</i>
functions.
The indices of the array are strings
consisting of the names of the environment variables,
and the value of each array element is
a string consisting of the value of that variable.
If the value of an environment variable is considered a
<i>numeric string</i>
(see
<xref href=awkexpr><a href="#tag_000_000_108_002">
Expressions in awk
</a></xref>),
the array element will also have its numeric value.

In all cases where the behaviour of
<i>awk</i>
is affected by environment variables
(including the environment of any commands that
<i>awk</i>
executes via the
<b>system</b>
function or via pipeline redirections with the
<b>print</b>
statement, the
<b>printf</b>
statement, or the
<b>getline</b>
function),
the environment used will be the environment at the time
<i>awk</i>
began executing;
it is implementation-dependent whether any modification of
<b>ENVIRON</b>
affects this environment.

<dt><b>FILENAME</b><dd>A pathname of the current input file.
Inside a
<b>BEGIN</b>
action the value is undefined.
Inside an
<b>END</b>
action the value is the name of the last
input file processed.

<dt><b>FNR</b><dd>The ordinal number of the current record
in the current file.
Inside a
<b>BEGIN</b>
action the value is zero.
Inside an
<b>END</b>
action the value is the number of the last record
processed in the last file processed.

<dt><b>FS</b><dd><index term="regular expressions"></index>
Input field separator regular expression;
a space character
by default.

<dt><b>NF</b><dd>The number of fields in the current record.
Inside a
<b>BEGIN</b>
action, the use of
<b>NF</b>
is undefined unless a
<b>getline</b>
function without a
<i>var</i>
argument is executed previously.
Inside an
<b>END</b>
action,
<b>NF</b>
will retain the value it had for the last record read, unless
a subsequent, redirected,
<b>getline</b>
function without a
<i>var</i>
argument is performed prior to entering the
<b>END</b>
action.

<dt><b>NR</b><dd>The ordinal number of the current record
from the start of input.
Inside a
<b>BEGIN</b>
action the value is zero.
Inside an
<b>END</b>
action
the value is the number of the last record processed.

<dt><b>OFMT</b><dd>The
<b>printf</b>
format for converting numbers to strings in
output statements (see
<xref href=awkout><a href="#tag_000_000_108_010">
Output Statements
</a></xref>);
%.6g
by default.
The result of the conversion is unspecified if the value of
<b>OFMT</b>
is not a floating-point format specification.

<dt><b>OFS</b><dd>The
<b>print</b>
statement output field separation;
a
space character
by default.

<dt><b>ORS</b><dd>The
<b>print</b>
statement output record separator;
a
newline character
by default.

<dt><b>RLENGTH</b><dd>The length of the string matched by the
<b>match</b>
function.

<dt><b>RS</b><dd>The first character of the string value of
<b>RS</b>
is the input record separator;
a
newline character
by default.
If
<b>RS</b>
contains more than one character,
the results are unspecified.
If
<b>RS</b>
is null, then records are separated by
sequences of one or more blank lines,
leading or trailing blank lines do not result in empty records at
the beginning or end of the input,
and a
newline character
is always a field separator, no matter what the value of
<b>FS</b>
is.

<dt><b>RSTART</b><dd>The starting position of the string matched by the <b>match</b>
function, numbering from 1.
This is always equivalent
to the return value of the <b>match</b> function.

<dt><b>SUBSEP</b><dd>The subscript separator string for multi-dimensional arrays;
the default value is implementation-dependent.

</dl>
<h5><a name = "tag_000_000_108_004">&nbsp;</a>Regular Expressions</h5>
<xref type="5" name="awkre"></xref>
The
<i>awk</i>
utility makes use of the extended regular expression notation (see
the <b>XBD</b> specification, <a href="../xbd/re.html#tag_007_004"><b>Extended Regular Expressions</b>&nbsp;</a> ) except that it will allow the use of
C-language conventions for escaping special characters within the EREs,
as specified in the table in the <b>XBD</b> specification, <a href="../xbd/notation.html"><b>File Format Notation</b>&nbsp;</a> 
(\\,
\a,
\b,
\f,
\n,
\r,
\t,
\v)
and the following table;
these escape sequences will be recognised both inside and outside
bracket expressions.
Note that records need not be separated by newline characters
and string constants can contain newline characters, so even the
\n
sequence is valid in
<i>awk</i>
EREs.
Using a slash character within the regular expression
requires the escaping shown in the following table:
<pre>
<table  bordercolor=#000000 border=1 align=center>
<tr valign=top><th align=center><b>Escape Sequence</b>
<th align=center><b>Description</b>
<th align=center><b>Meaning</b>
<tr valign=top><td align=center><b>\"</b>
<td align=left> Backslash quotation-mark 
<td align=left> Quotation-mark character 
<tr valign=top><td align=center><b>\/</b>
<td align=left> Backslash slash 
<td align=left> Slash character 
<tr valign=top><td align=center><b>\<i>ddd</i></b>
<td align=left> A backslash character followed by the longest sequence of one, two or three octal-digit characters (01234567). If all of the digits are 0, (that is, representation of the NUL character), the behaviour is undefined. 
<td align=left> The character whose encoding is represented by the one-, two- or three-digit octal integer. If the size of a byte on the system is greater than nine bits, the valid escape sequence used to represent a byte is implementation-dependent. Multi-byte characters require multiple, concatenated escape sequences of this type, including the leading \ for each byte. 
<tr valign=top><td align=center><b>\<i>c</i></b>
<td align=left> A backslash character followed by any character not described in this table or in the table in the <b>XBD</b> specification, <a href="../xbd/notation.html"><b>File Format Notation</b>&nbsp;</a>  (<code>\\,\a,\b,\f,\n,\r,\t,\v</code>)
<td align=left>Undefined
</table>
</pre>
<h6 align=center><xref table="Escape Sequences in <I>awk</i>"></xref>Table: Escape Sequences in <i>awk</i></h6>
<xref type="7" name="awkesc"></xref>
<p>
A regular expression can be matched against
a specific field or string by using one of the
two regular expression matching operators,
~
and
!~.
These operators interpret
their right-hand operand as a regular expression
and their left-hand operand as a string.
If the regular expression matches the string, the
~
expression
will evaluate to a value of
1,
and the
!~
expression will evaluate to a value of
0.
(The regular expression matching operation
is as defined by the term
matched in the <b>XBD</b> specification, <a href="../xbd/re.html#tag_007_001"><b>Regular Expression Definitions</b>&nbsp;</a> ,
where a match occurs on any part of the string
unless the regular expression is limited with the
circumflex or dollar sign special characters.)
If the regular expression does not match the string, the
~
expression will evaluate to a value of
0,
and the
!~
expression will evaluate to a value of
1.
If the right-hand operand is any expression other than the lexical token
<b>ERE</b>,
the string value of the expression will be interpreted as an extended
regular expression, including the escape conventions described above.
Note that these same escape conventions also will be
applied in the determining the
value of a string literal (the lexical token
<b>STRING</b>),
and thus will be applied a second time when a string literal is used in this
context.
<p>
When an
<b>ERE</b>
token appears as an expression in any context other than as the right-hand
of the
~
or
!~
operator or as one of the built-in
function arguments described below, the value of the resulting
expression will be the equivalent of:
<pre>
<code>
$0  ~  /<i>ere</i>/
</code>
</pre>
<p>
The
<i>ere</i>
argument to the
<b>gsub</b>,
<b>match</b>,
<b>sub</b>
functions, and the
<i>fs</i>
argument to the
<b>split</b>
function (see
<xref href=awkstr><a href="#tag_000_000_108_013">
String Functions
</a></xref>)
will be interpreted as extended regular expressions.
These can be either
<b>ERE</b>
tokens or arbitrary expressions,
and will be interpreted in the same manner as the right-hand side of the
~
or
!~
operator.
<p>
An extended regular expression
can be used to separate fields by
using the
<b>-F</b>&nbsp;<i>ERE</i>
option or by assigning
a string containing the expression to
the built-in variable
<b>FS</b>.
The default
value of the
<b>FS</b>
variable will be a single
space
character.
The following describes
<b>FS</b>
behaviour:
<ol>
<p>
<li>
If
<b>FS</b>
is a single character:
<ol type = a>
<p>
<li>
If
<b>FS</b>
is the
space character,
skip leading and trailing
blank characters;
fields will be delimited by sets of one or more
blank characters.
<p>
<li>
Otherwise, if
<b>FS</b>
is any other character
<i>c</i>,
fields will be delimited by
each single occurrence of
<i>c .</i>
<p>
</ol>
<p>
<li>
Otherwise,
the string value of
<b>FS</b>
will be considered to be an extended regular expression.
Each occurrence of
a sequence matching
the extended regular expression will delimit fields.
<p>
</ol>
<p>
Except in the
<b>gsub</b>,
<b>match</b>,
<b>split</b>
and
<b>sub</b>
built-in functions, regular expression matching will be based on input records;
that is, record separator characters (the first character of the value of
the variable
<b>RS</b>,
a
newline character
by default) cannot be embedded in the expression,
and no expression will match the record separator character.
If the record separator is not a
newline character,
newline characters embedded in the expression can be matched.
In those four built-in functions, regular expression matching will be
based on text strings; that is, any character
(including the
newline character
and the record separator) can be embedded in the pattern
and an appropriate pattern will match any character.
However, in all
<i>awk</i>
regular expression matching, the use of one or more NUL characters
in the pattern, input record or text string produces
undefined results.
<h5><a name = "tag_000_000_108_005">&nbsp;</a>Patterns</h5>
A
<i>pattern</i>
is any valid
<i>expression</i>,
a range specified by two expressions separated by comma,
or one of the two special patterns
<b>BEGIN</b>
or
<b>END</b>.
<h5><a name = "tag_000_000_108_006">&nbsp;</a>Special Patterns</h5>
The
<i>awk</i>
utility recognises two special patterns,
<b>BEGIN</b>
and
<b>END</b>.
Each
<b>BEGIN</b>
pattern will be matched once and its associated action
executed before the first
record of input is read
(except possibly by use of the
<b>getline</b>
function (see
<xref href=awkio><a href="#tag_000_000_108_014">
Input/Output and General Functions
</a></xref>)
in a prior
<b>BEGIN</b>
action) and before command line assignment is done.
Each
<b>END</b>
pattern will be matched once
and its associated action executed
after the last record of input has been read.
These two patterns will have associated actions.
<p>
<b>BEGIN</b>
and
<b>END</b>
will not combine with other patterns.
Multiple
<b>BEGIN</b>
and
<b>END</b>
patterns are allowed.
The actions associated with the
<b>BEGIN</b>
patterns will be
executed in the order specified in the program, as are the
<b>END</b>
actions.
An
<b>END</b>
pattern can precede a
<b>BEGIN</b>
pattern in a program.
<p>
If an
<i>awk</i>
program consists of only
actions with the pattern
<b>BEGIN</b>,
and the
<b>BEGIN</b>
action contains no
<b>getline</b>
function,
<i>awk</i>
will exit without reading its input when the last statement in the last
<b>BEGIN</b>
action is executed.
If an
<i>awk</i>
program consists of only
actions with the pattern
<b>END</b>
or only
actions with the patterns
<b>BEGIN</b>
and
<b>END</b>,
the input will be read before the statements in the
<b>END</b>
actions are executed.
<h5><a name = "tag_000_000_108_007">&nbsp;</a>Expression Patterns</h5>
An expression pattern will be evaluated
as if it were an expression in a Boolean context.
If the result is true, the
pattern will be considered to match,
and the associated action (if any)
will be executed.
If the result is false, the action will not be executed.
<h5><a name = "tag_000_000_108_008">&nbsp;</a>Pattern Ranges</h5>
A pattern range consists of two expressions
separated by a comma; in this case,
the action will be performed for all records
between a match of the first
expression and the following match
of the second expression, inclusive.
At this point,
the pattern range can be repeated starting at input
records subsequent
to the end of the matched range.
<h5><a name = "tag_000_000_108_009">&nbsp;</a>Actions</h5>
An action is a sequence of statements
as shown in the grammar in
<xref href=awkgram><a href="#tag_000_000_108_016">
Grammar
</a></xref>.
Any single statement can be replaced by
a statement list enclosed in braces.
The statements in a statement list must be separated by
newline characters
or semicolons,
and will be executed sequentially in the order that they appear.
<p>
The
<i>expression</i>
acting as the conditional in an
<b>if</b>
statement will be evaluated and if it is non-zero
or non-null,
the following
<i>statement</i>
will be executed; otherwise, if
<b>else</b>
is present, the statement following
the
<b>else</b>
will be executed.
<p>
The
<b>if</b>,
<b>while</b>,
<b>do</b>
...
<b>while</b>,
<b>for</b>,
<b>break</b>
and
<b>continue</b>
statements are based on the ISO&nbsp;C standard,
except that the Boolean expressions are treated as described in
<xref href=awkexpr><a href="#tag_000_000_108_002">
Expressions in awk
</a></xref>,
and except in the case of:
<pre>
<code>
for (<i>variable </i>in <i>array</i>)
</code>
</pre>
which will iterate, assigning each
<i>index</i>
of
<i>array</i>
to
<i>variable</i>
in an unspecified order.
The results of adding new elements to
<i>array</i>
within such a
<b>for</b>
loop are undefined.
If a
<b>break</b>
or
<b>continue</b>
statement occurs outside of a loop, the behaviour is undefined.
<p>
The
<b>delete</b>
statement will remove an individual array element.
Thus, the following code will delete an entire array:
<pre>
<code>
for (index in array)
    delete array[index]
</code>
</pre>
<p>
The
<b>next</b>
statement will cause all further
processing of the current input
record to be abandoned.
The behaviour is undefined if a
<b>next</b>
statement appears or is invoked in a
<b>BEGIN</b>
or
<b>END</b>
action.
<p>
The
<b>exit</b>
statement will invoke all
<b>END</b>
actions in the order in which they occur in the program source
and then terminate the program
without reading further input.
An
<b>exit</b>
statement inside an
<b>END</b>
action will terminate the program
without further execution of
<b>END</b>
actions.
If an expression is specified in an
<b>exit</b>
statement, its numeric value will be the exit status of
<i>awk</i>,
unless subsequent errors are encountered or a subsequent
<b>exit</b>
statement with an expression is executed.
<h5><a name = "tag_000_000_108_010">&nbsp;</a>Output Statements</h5>
<xref type="5" name="awkout"></xref>
Both
<b>print</b>
and
<b>printf</b>
statements write to standard output by default.
The output is written to the location specified by
<i>output_redirection</i>
if one is supplied, as follows:
<pre>
<code>
> <i>expression</i>
>&gt; <i>expression</i>
| <i>expression</i>
</code>
</pre>
<p>
In all cases, the
<i>expression</i>
will be evaluated to produce a string that is used as a full pathname
to write into (for
"&gt;" or "&gt;&gt;")
or as a command to be executed (for "|").
Using the first two forms, if the file of that name is not
currently open, it will be opened, creating it if necessary and using the
first form, truncating the file.
The output then will be appended to the file.
As long as the file remains open,
subsequent calls in which
<i>expression</i>
evaluates to the same string value simply will append output to the file.
The file remains open until the
<b>close</b>
function (see
<xref href=awkio><a href="#tag_000_000_108_014">
Input/Output and General Functions
</a></xref>)
is called with an expression that evaluates to the same string value.
<p>
The third form will write output onto a stream
piped to the input of a command.
The stream will be created if no stream is currently open with the value of
<i>expression</i>
as its command name.
The stream created will be equivalent to one created by a call to the <b>XSH</b> specification
<i><a href="../xsh/popen.html">popen()</a></i>
function with the value of
<i>expression</i>
as the
<i>command</i>
argument and a value of
<b>w</b>
as the
<i>mode</i>
argument.
As long as the stream remains open,
subsequent calls in which
<i>expression</i>
evaluates to the same
string value will write output to the existing stream.
The stream will remain open until the
<b>close</b>
function (see
<xref href=awkio><a href="#tag_000_000_108_014">
Input/Output and General Functions
</a></xref>)
is called with an expression that evaluates to the same string value.
At that time, the stream will be closed as if by a call to the <b>XSH</b> specification
<i><a href="../xsh/pclose.html">pclose()</a></i>
function.
<p>
As described in detail by the grammar in
<xref href=awkgram><a href="#tag_000_000_108_016">
Grammar
</a></xref>,
these output statements take a comma-separated list of
<i>expression</i>s
referred in the grammar by the non-terminal symbols
<b>expr_list</b>,
<b>print_expr_list</b>
or
<b>print_expr_list_opt</b>.
This list is referred to here as the
<i>expression list ,</i>
and each member is referred to as an
<i>expression argument .</i>
<p>
The
<b>print</b>
statement will write the value of each expression argument
onto the indicated output stream separated by the current output
field separator (see variable
<b>OFS</b>
above), and terminated by the output record separator (see variable
<b>ORS</b>
above).
All expression arguments
will be taken as strings, being converted if necessary;
this conversion will be as described in
<xref href=awkexpr><a href="#tag_000_000_108_002">
Expressions in awk
</a></xref>,
with the exception that the
<b>printf</b>
format in
<b>OFMT</b>
will be used instead of the value in
<b>CONVFMT</b>.
An empty expression list will stand for the whole input record
($0).
<p>
The
<b>printf</b>
statement will produce output based on a notation similar to the File Format
Notation used to describe file formats in this specification (see
the <b>XBD</b> specification, <a href="../xbd/notation.html"><b>File Format Notation</b>&nbsp;</a> ).
Output will be produced as specified with
the first expression argument as the string
&lt;<i>format</i>&gt;
and subsequent expression arguments as the strings
&lt;<i>arg1</i>&gt;
to
&lt;<i>argn</i>&gt;,
inclusive, with the following exceptions:
<ol>
<p>
<li>
The
<i>format</i>
will be an actual character string rather than a graphical representation.
Therefore, it cannot contain empty character positions.
The space character in the
<i>format</i>
string, in any context other than a
<i>flag</i>
of a conversion specification,
will be treated as an ordinary character that is copied to the output.
<p>
<li>
If the character set contains a <img src="../images/delta.gif" border=0> character and that character appears
in the
<i>format</i>
string, it will be treated as an
ordinary character that is copied to the output.
<p>
<li>
The
<i>escape sequences</i>
beginning with a backslash character will be treated as sequences of
ordinary characters that are copied to the output.
Note that these same sequences will be interpreted lexically by
<i>awk</i>
when they appear in literal strings, but they will not be treated specially
by the
<b>printf</b>
statement.
<p>
<li>
A
<i>field width</i>
or
<i>precision</i>
can be specified as the "*"
character instead of a digit string.
In this case the next argument from the expression list will be fetched
and its numeric value taken as the field width or precision.
<p>
<li>
The implementation will not precede or follow output from the
d
or
u
conversion specifications with
blank characters
not specified by the
<i>format</i>
string.
<p>
<li>
The implementation will not precede output from the
o
conversion specification with leading zeros not specified by the
<i>format</i>
string.
<p>
<li>
For the
c
conversion specification:
if the argument has a numeric value, the character whose encoding is that
value will be output.
If the value is zero or is not the encoding of any character in the
character set, the behaviour is undefined.
If the argument does not have a numeric value, the first character
of the string value will be output;
if the string does not contain any characters the behaviour is undefined.
<p>
<li>
For each conversion specification that consumes an argument,
the next expression argument will be evaluated.
With the exception of the
c
conversion, the value will be converted
(according to the rules specified in
<xref href=awkexpr><a href="#tag_000_000_108_002">
Expressions in awk
</a></xref>)
to the appropriate type for the conversion specification.
<p>
<li>
If there are insufficient expression arguments to satisfy all the
conversion specifications in the
<i>format</i>
string, the behaviour is undefined.
<p>
<li>
If any character sequence in the
<i>format</i>
string begins with a % character, but does not form a
valid conversion specification, the behaviour is unspecified.
<p>
</ol>
<p>
Both
<b>print</b>
and
<b>printf</b>
can output at least
{LINE_MAX}
bytes.
<h5><a name = "tag_000_000_108_011">&nbsp;</a>Functions</h5>
The
<i>awk</i>
language
has a variety of built-in functions: arithmetic, string, input/output
and general.
<h5><a name = "tag_000_000_108_012">&nbsp;</a>Arithmetic Functions</h5>
The arithmetic functions, except for
<b>int</b>,
are based on the ISO&nbsp;C standard.
The behaviour is undefined in cases where the ISO&nbsp;C standard
specifies that an error be returned or that the behaviour is undefined.
Although the grammar (see
<xref href=awkgram><a href="#tag_000_000_108_016">
Grammar
</a></xref>)
permits built-in functions to appear
with no arguments or parentheses, unless the argument or
parentheses are indicated as optional in the following
list (by displaying them within the
<b>[&nbsp;]</b>
brackets), such use is undefined.
<dl compact>

<dt>atan2(<i>y</i>,<i>x</i>)<dd>
Return arctangent of
<i>y</i>/<i>x</i>.

<dt>cos(<i>x</i>)<dd>Return cosine of
<i>x</i>,
where
<i>x</i>
is in radians.

<dt>sin(<i>x</i>)<dd>Return sine of
<i>x</i>,
where
<i>x</i>
is in radians.

<dt>exp(<i>x</i>)<dd>Return
the exponential function of <i>x</i>.

<dt>log(<i>x</i>)<dd>Return the natural logarithm of <i>x</i>.

<dt>sqrt(<i>x</i>)<dd>
Return the square root of <i>x</i>.

<dt>int(<i>x</i>)<dd>Truncate its argument to an integer.
It will be truncated toward 0 when
<i>x</i>
&gt; 0.

<dt>rand()<dd>Return a random number
<i>n</i>,
such that
0 &lt;=
<i>n</i>
&lt; 1.

<dt>srand(<b>[</b><i>expr</i><b>]</b>)<dd>
Set the seed value for
<b>rand</b>
to
<i>expr</i>
or use the time of day if
<i>expr</i> is omitted.
The previous seed value will be returned.

</dl>
<h5><a name = "tag_000_000_108_013">&nbsp;</a>String Functions</h5>
<xref type="5" name="awkstr"></xref>
The string functions in the following list shall be supported.
Although the grammar (see
<xref href=awkgram><a href="#tag_000_000_108_016">
Grammar
</a></xref>)
permits built-in functions to appear
with no arguments or parentheses, unless the argument or
parentheses are indicated as optional in the following
list (by displaying them within the
<b>[&nbsp;]</b>
brackets), such use is undefined.
<dl compact>

<dt>gsub(<i>ere</i>,<i> repl</i><b>[</b>,<i>in</i><b>]</b>)<dd>
Behave like
<b>sub</b>
(see below),
except that it will replace all occurrences
of the regular expression
(like the
<i><a href="ed.html">ed</a></i>
utility global substitute) in
$0
or in the
<i>in</i>
argument, when specified.

<dt>index(<i>s</i>,<i> t</i>)<dd>
Return the position, in characters, numbering from 1, in string
<i>s</i>
where string
<i>t</i>
first occurs, or zero if it does not occur at all.

<dt>length<b>[</b>(<b>[</b><i>s</i><b>]</b>)<b>]</b><dd>
Return the length, in characters, of its argument taken as a string,
or of the whole
record,
$0,
if there is no argument.
The use of no argument and no parentheses with
<b>length</b>
is obsolescent in the ISO/IEC 9945-2:1993 standard;
to be fully portable to POSIX systems, the application must use
length($0)
for the length of the whole record.
However, XSI-conformant systems will continue to support
this usage indefinitely.

<dt>match(<i>s</i>,<i> ere</i>)<dd>
Return the position, in characters, numbering from 1, in string
<i>s</i>
where the extended regular expression
<i>ere</i>
occurs, or zero if it does not occur at all.
RSTART will be set to the starting position (which is
the same as the returned value), zero if no match is found;
RLENGTH
will be set to the length of the matched string, -1 if no match is found.

<dt>split(<i>s</i>,<i> a</i><b>[</b>,<i>fs</i><b>]</b>)<dd>
Split the string
<i>s</i>
into array elements
<i>a [1],</i>
<i>a [2],</i>
...
<i>a [ n</i>
and return
<i>n .</i>
The separation will be done with the extended regular expression
<i>fs</i>
or with the field separator
<b>FS</b>
if
<i>fs</i>
is not given.
Each array element will have a string value when created.
If the string assigned to any array element,
with any occurrence of the decimal-point character from the
current locale changed to a
period character,
would be considered a
<i>numeric string</i>
(see
<xref href=awkexpr><a href="#tag_000_000_108_002">
Expressions in awk
</a></xref>),
the array element will also have the numeric value of the
<i>numeric string .</i>
The effect of a null string as the value of
<i>fs</i>
is unspecified.

<dt>sprintf(<i>fmt</i>,<i> expr</i>,<i> expr</i>, ...)<dd>
Format the expressions according to the
<b>printf</b>
format given by
<i>fmt</i>
and return the resulting string.

<dt>sub(<i>ere</i>,<i> repl</i><b>[</b>,<i>in</i><b>]</b>)<dd>
Substitute the string
<i>repl</i>
in place of the first instance of
the extended regular expression
<i>ERE</i>
in string
<i>in</i>
and return the number of substitutions.
An ampersand
(&amp;)
appearing in the string
<i>repl</i>
will be replaced by the string from
<i>in</i>
that matches the regular expression.
For each occurrence of backslash (\) encountered when scanning the
string
<i>repl</i>
from beginning to end, the next character is
taken literally and loses its special meaning (for example, \&amp; will be
interpreted as a literal ampersand character).
Except for &amp; and \,
it is unspecified what the special meaning of any such character is.
If
<i>in</i>
is specified and it is not an
<i>lvalue</i>
(see
<xref href=awkexpr><a href="#tag_000_000_108_002">
Expressions in awk
</a></xref>),
the behaviour is undefined.
If
<i>in</i>
is omitted,
<i>awk</i>
will substitute in the current record
($0).

<dt>substr(<i>s</i>,<i> m</i><b>[</b>,<i>n</i><b>]</b>)<dd>
Return the at most
<i>n -character</i>
substring of
<i>s</i>
that begins at position
<i>m</i>,
numbering from 1.
If
<i>n</i>
is missing,
the length of the substring will be limited by the length of the string
<i>s .</i>

<dt>tolower(<i>s</i>)<dd>
Return a string based on the string
<i>s .</i>
Each character in
<i>s</i>
that is an upper-case letter specified to have a
<b>tolower</b>
mapping by the
LC_CTYPE
category of the current locale will be replaced in the returned string
by the lower-case letter specified by the mapping.
Other characters in
<i>s</i>
will be unchanged in the returned string.

<dt>toupper(<i>s</i>)<dd>
Return a string based on the string
<i>s .</i>
Each character in
<i>s</i>
that is a lower-case letter specified to have a
<b>toupper</b>
mapping by the
LC_CTYPE
category of the current locale will be replaced in the returned string
by the upper-case letter specified by the mapping.
Other characters in
<i>s</i>
will be unchanged in the returned string.

</dl>
<p>
All of the preceding functions that take
<i>ERE</i>
as a parameter expect a pattern or a string valued expression that
is a regular expression as defined in
<xref href=awkre><a href="#tag_000_000_108_004">
Regular Expressions
</a></xref>.
<h5><a name = "tag_000_000_108_014">&nbsp;</a>Input/Output and General Functions</h5>
<xref type="5" name="awkio"></xref>
The input/output and general functions are:
<dl compact>

<dt>close(<i>expression</i>)<dd>
Close the file or pipe
opened by a
<b>print</b>
or
<b>printf</b>
statement or a call to
<b>getline</b>
with the same string-valued
<i>expression</i>.
The limit on the number of open
<i>expression</i>
arguments is implementation-dependent.
If the close was successful, the function will return zero;
otherwise, it will return non-zero.

<dt>expression | getline [<i>var</i>]<dd>
Read a record of input from a stream piped from the output of a command.
The stream will be created if no stream is currently open with the value of
<i>expression</i>
as its command name.
The stream created will be
equivalent to one created by a call to the
<i><a href="../xsh/popen.html">popen()</a></i>
function with the value of
<i>expression</i>
as the
<i>command</i>
argument and a value of
<b>r</b>
as the
<i>mode</i>
argument.
As long as the stream remains open,
subsequent calls in which
<i>expression</i>
evaluates to the same string value will read subsequent records from the file.
The stream will remain open until the
<b>close</b>
function
is called with an expression that evaluates to the same string value.
At that time, the stream will be closed as if by a call to the
<i><a href="../xsh/pclose.html">pclose()</a></i>
function.
If
<i>var</i>
is missing,
$0
and
<b>NF</b>
will be set;
otherwise,
<i>var</i>
will be set.

The
<b>getline</b>
operator can form ambiguous constructs when there
are unparenthesised operators (including concatenate) to the
left of the "|"
(to the beginning of the expression containing
<b>getline</b>).
In the context of the "$"
operator, "|"
behaves as if it had a lower precedence than "$".
The result of evaluating
other operators is unspecified, and portable applications must
parenthesise properly all such usages.

<dt>getline<dd>
Set
$0
to the next input record from the current input file.
This form of
<b>getline</b>
will set the
<b>NF</b>,
<b>NR</b>
and
<b>FNR</b>
variables.

<dt>getline<i> var</i><dd>
Set variable
<i>var</i>
to the next input record from the current input file.
This form of
<b>getline</b>
will set the
<b>FNR</b>
and
<b>NR</b>
variables.

<dt>getline <b>[</b><i>var</i><b>] </b>&lt; <i>expression</i><dd>
Read the next record of input from a named file.
The
<i>expression</i>
will be evaluated to produce a string that is used as a full pathname.
If the file of that name is not
currently open, it will be opened.
As long as the stream remains open,
subsequent calls in which
<i>expression</i>
evaluates to the same string value will read subsequent records from the file.
The file will remain open until the
<b>close</b>
function is called with an expression that evaluates to the same string value.
If
<i>var</i>
is missing,
$0
and
<b>NF</b>
will be set;
otherwise,
<i>var</i>
will be set.

The
<b>getline</b>
operator can form ambiguous constructs when there
are unparenthesised binary operators (including concatenate)
to the right of the
"&lt;"
(up to the end of the expression containing the
<b>getline</b>).
The result of evaluating such a construct
is unspecified, and portable applications must parenthesise properly all
such usages.

<dt>system(<i>expression</i>)<dd>
Execute the command given by
<i>expression</i>
in a manner
equivalent to the <b>XSH</b> specification
<i><a href="../xsh/system.html">system()</a></i>
function
and return the exit status of the command.

</dl>
<p>
All forms of
<b>getline</b>
will return 1 for successful input, zero
for end-of-file, and -1 for an error.
<p>
Where strings are used as
the name of a file or pipeline, the strings must be textually identical.
The terminology &quot;same string value&quot; implies that
&quot;equivalent strings&quot;, even those that differ only by
space characters,
represent different files.
<h5><a name = "tag_000_000_108_015">&nbsp;</a>User-defined Functions</h5>
<xref type="5" name="awkuser"></xref>
The
<i>awk</i>
language also provides user-defined functions.
Such functions can be defined as:
<pre>
<code>
function <i>name</i>(<i>args</i>,...) {<i> statements</i> }
</code>
</pre>
<p>
A function can be referred to anywhere in an
<i>awk</i>
program; in
particular,
its use can precede its definition.
The scope of a function will be global.
<p>
Function arguments can be either scalars or arrays; the behaviour
is undefined if an array name is passed as an argument that the
function uses as a scalar, or if a scalar expression is passed
as an argument that the function uses as an array.
Function arguments will be passed by value
if scalar and by reference if array name.
Argument names will be local to the function;
all other variable names will be global.
The same name will not be used as both an
argument name and as the name of a function or a special
<i>awk</i>
variable.
The same name must not be used both as a variable
name with global scope and as the name of a function.
The same name must not be used within the same scope both as a scalar
variable and as an array.
<p>
The number of parameters in the function definition need not
match the number of parameters in the function call.
Excess formal parameters can be used as local variables.
If fewer arguments are supplied in a function call than are in the
function definition, the extra parameters that are used in the
function body as scalars will be initialised with a string value
of the null string and a numeric value of zero, and the extra
parameters that are used in the function body as arrays will be
initialised as empty arrays.
If more arguments are supplied in a function call than are in
the function definition, the behaviour is undefined.
<p>
When invoking a function,
no white space can be placed between the function name and the
opening parenthesis.
Function calls can be nested
and recursive calls can be made upon functions.
Upon return from any nested or recursive function call,
the values of all of the calling function's parameters
will be unchanged, except for array parameters passed by reference.
The
<b>return</b>
statement can be used to return a value.
If a
<b>return</b>
statement appears outside of a function definition,
the behaviour is undefined.
<p>
In the function definition,
newline characters
are optional before the opening brace and after the closing brace.
Function definitions can appear anywhere in the program where a
<i>pattern-action</i>
pair is allowed.
<h5><a name = "tag_000_000_108_016">&nbsp;</a>Grammar</h5>
<xref type="5" name="awkgram"></xref>
The grammar in this section and the lexical
conventions in the following section will together describe the syntax for
<i>awk</i>
programs.
The general conventions for this style of grammar are described in
<xref href=grammar></xref>.
A valid program can be represented as the non-terminal symbol
<i>program</i>
in the grammar.
This formal syntax takes precedence over
the preceding text syntax description.
<pre>
<code>
%token NAME NUMBER STRING ERE
%token FUNC_NAME   /* name followed by '(' without white space */

/* Keywords  */
%token       Begin   End
/*          'BEGIN' 'END'                            */

%token       Break   Continue   Delete   Do   Else
/*          'break' 'continue' 'delete' 'do' 'else'  */

%token       Exit   For   Function   If   In
/*          'exit' 'for' 'function' 'if' 'in'        */

%token       Next   Print   Printf   Return   While
/*          'next' 'print' 'printf' 'return' 'while' */

/* Reserved function names */
%token BUILTIN_FUNC_NAME
            /* one token for the following:
             * atan2 cos sin exp log sqrt int rand srand
             * gsub index length match split sprintf sub
             * substr tolower toupper close system
             */
%token GETLINE
            /* Syntactically different from other built-ins */

/* Two-character tokens */
%token ADD_ASSIGN SUB_ASSIGN MUL_ASSIGN DIV_ASSIGN MOD_ASSIGN POW_ASSIGN
/*     '+='       '-='       '*='       '/='       '%='       '^=' */

%token  OR   AND  NO_MATCH   EQ   LE   GE   NE   INCR  DECR  APPEND
/*      '||' '&amp;&amp;' '!' '==' '&lt;=' '&gt;=' '!=' '++'  '--'  '&gt;&gt;'   */

/* One-character tokens */
%token '{' '}' '(' ')' '[' ']' ',' ';' NEWLINE
%token '+' '-' '*' '%' '^' '!' '&gt;' '&lt;' '|' '?' ':' '~' '$' '='

%start program
%%

program          : item_list
                 | actionless_item_list
                 ;

item_list        : newline_opt
                 | actionless_item_list item terminator
                 | item_list            item terminator
                 | item_list          action terminator
                 ;

actionless_item_list : item_list            pattern terminator
                 | actionless_item_list pattern terminator
                 ;

item             : pattern action
                 | Function NAME      '(' param_list_opt ')'
                       newline_opt action
                 | Function FUNC_NAME '(' param_list_opt ')'
                       newline_opt action
                 ;

param_list_opt   : /* empty */
                 | param_list
                 ;

param_list       : NAME
                 | param_list ',' NAME
                 ;

pattern          : Begin
                 | End
                 | expr
                 | expr ',' newline_opt expr
                 ;

action           : '{' newline_opt                             '}'
                 | '{' newline_opt terminated_statement_list   '}'
                 | '{' newline_opt unterminated_statement_list '}'
                 ;

terminator       : terminator ';'
                 | terminator NEWLINE
                 |            ';'
                 |            NEWLINE
                 ;

terminated_statement_list : terminated_statement
                 | terminated_statement_list terminated_statement
                 ;

unterminated_statement_list : unterminated_statement
                 | terminated_statement_list unterminated_statement
                 ;

terminated_statement : action newline_opt
                 | If '(' expr ')' newline_opt terminated_statement
                 | If '(' expr ')' newline_opt terminated_statement
                       Else newline_opt terminated_statement
                 | While '(' expr ')' newline_opt terminated_statement
                 | For '(' simple_statement_opt ';'
                      expr_opt ';' simple_statement_opt ')' newline_opt
                      terminated_statement
                 | For '(' NAME In NAME ')' newline_opt
                      terminated_statement
                 | ';' newline_opt
                 | terminatable_statement NEWLINE newline_opt
                 | terminatable_statement ';'     newline_opt
                 ;

unterminated_statement : terminatable_statement
                 | If '(' expr ')' newline_opt unterminated_statement
                 | If '(' expr ')' newline_opt terminated_statement
                      Else newline_opt unterminated_statement
                 | While '(' expr ')' newline_opt unterminated_statement
                 | For '(' simple_statement_opt ';'
                  expr_opt ';' simple_statement_opt ')' newline_opt
                      unterminated_statement
                 | For '(' NAME In NAME ')' newline_opt
                      unterminated_statement
                 ;

terminatable_statement : simple_statement
                 | Break
                 | Continue
                 | Next
                 | Exit expr_opt
                 | Return expr_opt
                 | Do newline_opt terminated_statement While '(' expr ')'
                 ;

simple_statement_opt : /* empty */
                 | simple_statement
                 ;

simple_statement : Delete NAME '[' expr_list ']'
                 | expr
                 | print_statement
                 ;

print_statement  : simple_print_statement
                 | simple_print_statement output_redirection
                 ;

simple_print_statement : Print  print_expr_list_opt
                 | Print  '(' multiple_expr_list ')'
                 | Printf print_expr_list
                 | Printf '(' multiple_expr_list ')'
                 ;

output_redirection : '&gt;'    expr
                 | APPEND expr
                 | '|'    expr
                 ;

expr_list_opt    : /* empty */
                 | expr_list
                 ;

expr_list        : expr
                 | multiple_expr_list
                 ;

multiple_expr_list : expr ',' newline_opt expr
                 | multiple_expr_list ',' newline_opt expr
                 ;

expr_opt         : /* empty */
                 | expr
                 ;

expr             : unary_expr
                 | non_unary_expr
                 ;

unary_expr       : '+' expr
                 | '-' expr
                 | unary_expr '^'      expr
                 | unary_expr '*'      expr
                 | unary_expr '/'      expr
                 | unary_expr '%'      expr
                 | unary_expr '+'      expr
                 | unary_expr '-'      expr
                 | unary_expr          non_unary_expr
                 | unary_expr '&lt;'      expr
                 | unary_expr LE       expr
                 | unary_expr NE       expr
                 | unary_expr EQ       expr
                 | unary_expr '&gt;'      expr
                 | unary_expr GE       expr
                 | unary_expr '~'      expr
                 | unary_expr NO_MATCH expr
                 | unary_expr In NAME
                 | unary_expr AND newline_opt expr
                 | unary_expr OR  newline_opt expr
                 | unary_expr '?' expr ':' expr
                 | unary_input_function
                 ;

non_unary_expr   : '(' expr ')'
                 | '!' expr
                 | non_unary_expr '^'      expr
                 | non_unary_expr '*'      expr
                 | non_unary_expr '/'      expr
                 | non_unary_expr '%'      expr
                 | non_unary_expr '+'      expr
                 | non_unary_expr '-'      expr
                 | non_unary_expr          non_unary_expr
                 | non_unary_expr '&lt;'      expr
                 | non_unary_expr LE       expr
                 | non_unary_expr NE       expr
                 | non_unary_expr EQ       expr
                 | non_unary_expr '&gt;'      expr
                 | non_unary_expr GE       expr
                 | non_unary_expr '~'      expr
                 | non_unary_expr NO_MATCH expr
                 | non_unary_expr In NAME
                 | '(' multiple_expr_list ')' In NAME
                 | non_unary_expr AND newline_opt expr
                 | non_unary_expr OR  newline_opt expr
                 | non_unary_expr '?' expr ':' expr
                 | NUMBER
                 | STRING
                 | lvalue
                 | ERE
                 | lvalue INCR
                 | lvalue DECR
                 | INCR lvalue
                 | DECR lvalue
                 | lvalue POW_ASSIGN expr
                 | lvalue MOD_ASSIGN expr
                 | lvalue MUL_ASSIGN expr
                 | lvalue DIV_ASSIGN expr
                 | lvalue ADD_ASSIGN expr
                 | lvalue SUB_ASSIGN expr
                 | lvalue '=' expr
                 | FUNC_NAME '(' expr_list_opt ')'
                      /* no white space allowed before '(' */
                 | BUILTIN_FUNC_NAME '(' expr_list_opt ')'
                 | BUILTIN_FUNC_NAME
                 | non_unary_input_function
                 ;

print_expr_list_opt : /* empty */
                 | print_expr_list
                 ;

print_expr_list  : print_expr
                 | print_expr_list ',' newline_opt print_expr
                 ;

print_expr       : unary_print_expr
                 | non_unary_print_expr
                 ;

unary_print_expr : '+' print_expr
                 | '-' print_expr
                 | unary_print_expr '^'      print_expr
                 | unary_print_expr '*'      print_expr
                 | unary_print_expr '/'      print_expr
                 | unary_print_expr '%'      print_expr
                 | unary_print_expr '+'      print_expr
                 | unary_print_expr '-'      print_expr
                 | unary_print_expr          non_unary_print_expr
                 | unary_print_expr '~'      print_expr
                 | unary_print_expr NO_MATCH print_expr
                 | unary_print_expr In NAME
                 | unary_print_expr AND newline_opt print_expr
                 | unary_print_expr OR  newline_opt print_expr
                 | unary_print_expr '?' print_expr ':' print_expr
                 ;

non_unary_print_expr : '(' expr ')'
                 | '!' print_expr
                 | non_unary_print_expr '^'      print_expr
                 | non_unary_print_expr '*'      print_expr
                 | non_unary_print_expr '/'      print_expr
                 | non_unary_print_expr '%'      print_expr
                 | non_unary_print_expr '+'      print_expr
                 | non_unary_print_expr '-'      print_expr
                 | non_unary_print_expr          non_unary_print_expr
                 | non_unary_print_expr '~'      print_expr
                 | non_unary_print_expr NO_MATCH print_expr
                 | non_unary_print_expr In NAME
                 | '(' multiple_expr_list ')' In NAME
                 | non_unary_print_expr AND newline_opt print_expr
                 | non_unary_print_expr OR  newline_opt print_expr
                 | non_unary_print_expr '?' print_expr ':' print_expr
                 | NUMBER
                 | STRING
                 | lvalue
                 | ERE
                 | lvalue INCR
                 | lvalue DECR
                 | INCR lvalue
                 | DECR lvalue
                 | lvalue POW_ASSIGN print_expr
                 | lvalue MOD_ASSIGN print_expr
                 | lvalue MUL_ASSIGN print_expr
                 | lvalue DIV_ASSIGN print_expr
                 | lvalue ADD_ASSIGN print_expr
                 | lvalue SUB_ASSIGN print_expr
                 | lvalue '=' print_expr
                 | FUNC_NAME '(' expr_list_opt ')'
                     /* no white space allowed before '(' */
                 | BUILTIN_FUNC_NAME '(' expr_list_opt ')'
                 | BUILTIN_FUNC_NAME
                 ;

lvalue           : NAME
                 | NAME '[' expr_list ']'
                 | '$' expr
                 ;

non_unary_input_function : simple_get
                 | simple_get '&lt;' expr
                 | non_unary_expr '|' simple_get
                 ;

unary_input_function : unary_expr '|' simple_get
                 ;

simple_get       : GETLINE
                 | GETLINE lvalue
                 ;

newline_opt      : /* empty */
                 | newline_opt NEWLINE
                 ;
</code>
</pre>
<p>
This grammar has several ambiguities that are resolved as follows:
<ul>
<p>
<li>
Operator precedence and associativity are as described in
<xref href=awkprec></xref>.
<p>
<li>
In case of ambiguity, an
<b>else</b>
will be associated
with the most immediately preceding
<b>if</b>
that would satisfy the grammar.
<p>
<li>
In some contexts, a slash
(/)
that is used to surround an ERE could also
be the division operator.
This is resolved in such
a way that wherever the division operator could appear,
a slash is assumed to be the division operator.
(There is no unary division operator.)
<p>
</ul>
<p>
One convention that might not be obvious from the formal grammar
is where
newline characters
are acceptable.
There are several obvious placements such as terminating a statement,
and a backslash can be used to escape
newline characters
between any lexical tokens.
In addition,
newline characters
without backslashes can follow a comma,
an open brace,
logical AND operator (<b>&amp;&amp;</b>),
logical OR operator (<b>||</b>),
the
<b>do</b>
keyword,
the
<b>else</b>
keyword,
and the closing parenthesis of an
<b>if</b>,
<b>for</b>
or
<b>while</b>
statement.
For example:
<pre>
<code>
{ print  $1,
         $2 }
</code>
</pre>
<h5><a name = "tag_000_000_108_017">&nbsp;</a>Lexical Conventions</h5>
The lexical conventions for
<i>awk</i>
programs, with respect to the preceding grammar, are as follows:
<ol>
<p>
<li>
Except as noted,
<i>awk</i>
will recognise the longest possible
token or delimiter beginning at a given point.
<p>
<li>
A comment consists of any characters beginning with the
number sign character and terminated by, but excluding the next
occurrence of, a
newline
character.
Comments will have no effect, except to delimit lexical tokens.
<p>
<li>
The character
newline
will be recognised as the token
<b>NEWLINE</b>.
<p>
<li>
A backslash character immediately followed by a
newline
character will have no effect.
<p>
<li>
The token
<b>STRING</b>
represents a string constant.
A string constant begins with the character
 .
Within a string
constant, a backslash character will be considered to begin an escape
sequence as specified in the table in
the <b>XBD</b> specification, <a href="../xbd/notation.html"><b>File Format Notation</b>&nbsp;</a> 
(\\,
\a,
\b,
\f,
\n,
\r,
\t,
\v).
In addition, the
escape sequences in
<xref href=awkesc></xref>
will be recognised.
A
newline
character will not occur within a string constant.
A string constant will be terminated by the first unescaped occurrence of the
character

after the one that begins the string constant.
The value of the string will be the sequence of all unescaped characters
and values of escape sequences between, but not including, the two
delimiting

characters.
<p>
<li>
The token
<b>ERE</b>
represents an extended regular expression constant.
An ERE constant begins with the slash character.
Within an ERE constant, a
backslash
character will be considered to begin
an escape sequence as specified in the table in
the <b>XBD</b> specification, <a href="../xbd/notation.html"><b>File Format Notation</b>&nbsp;</a> .
In addition, the escape sequences in
<xref href=awkesc></xref>
will be recognised.
A
newline
character must not occur within an ERE constant.
An ERE constant will be terminated by the first unescaped occurrence of
the slash character after the one that begins the string constant.
The extended regular expression represented by the ERE constant
will be the sequence of all unescaped characters and values of escape
sequences between, but not including, the two delimiting slash characters.
<p>
<li>
A
blank character
has no effect, except to delimit lexical tokens or within
<b>STRING</b>
or
<b>ERE</b>
tokens.
<p>
<li>
The token
<b>NUMBER</b>
represents a numeric constant.
Its form and numeric value are equivalent to either of the tokens
<b>floating-constant</b>
or
<b>integer-constant</b>
as specified by the ISO&nbsp;C standard,
with the following exceptions:
<ol type = a>
<p>
<li>
An integer constant cannot begin with
0x
or include the hexadecimal digits
a,
b,
c,
d,
e,
f,
A,
B,
C,
D,
E
or
F.
<p>
<li>
The value of an integer constant beginning with
0
will be taken in decimal rather than octal.
<p>
<li>
An integer constant cannot include a suffix
(u,
U,
l
or
L).
<p>
<li>
A floating constant cannot include a suffix
(f,
F,
l
or
L).
<p>
</ol>
<p>
If the value is too large or too small to be representable,
the behaviour is undefined.
<p>
<li>
A sequence of underscores, digits and alphabetics from the
portable character set (see
the <b>XBD</b> specification, <a href="../xbd/charset.html#tag_001_001"><b>Portable Character Set</b>&nbsp;</a> ),
beginning with an underscore
or alphabetic, will be considered a word.
<p>
<li>
The following words are keywords that will be recognised as
individual tokens; the name of the token is the same as the
keyword:
<pre>
<dl compact><dt> <dd>
<table <tr valign=top><th align=left>BEGIN
<th align=left>delete
<th align=left>for
<th align=left>in
<th align=left>printf
<tr valign=top><td align=left>END
<td align=left>do
<td align=left>function
<td align=left>next
<td align=left>return
<tr valign=top><td align=left>break
<td align=left>else
<td align=left>getline
<td align=left>print
<td align=left>while
<tr valign=top><td align=left>continue
<td align=left>exit
<td align=left>if
</table>
</dl>
</pre>
<br>
<p>
<li>
The following words are names of built-in functions and
will be recognised as the token
<b>BUILTIN_FUNC_NAME</b>:
<pre>
<dl compact><dt> <dd>
<table <tr valign=top><th align=left>atan2
<th align=left>index
<th align=left>match
<th align=left>sprintf
<th align=left>substr
<tr valign=top><td align=left>close
<td align=left>int
<td align=left>rand
<td align=left>sqrt
<td align=left>system
<tr valign=top><td align=left>cos
<td align=left>length
<td align=left>sin
<td align=left>srand
<td align=left>tolower
<tr valign=top><td align=left>exp
<td align=left>log
<td align=left>split
<td align=left>sub
<td align=left>toupper
<tr valign=top><td align=left>gsub
</table>
</dl>
</pre>
<p>
The above-listed keywords and names of built-in functions are
considered reserved words.
<p>
<li>
The token
<b>NAME</b>
consists of a word that is not a keyword or a
name of a built-in function and is not followed immediately
(without any delimiters) by the
"("
character.
<p>
<li>
The token
<b>FUNC_NAME</b>
consists of a word that is not a keyword or
a name of a built-in function, followed immediately (without any
delimiters) by the
"("
character.
The
"("
character will not be included as part of the token.
<p>
<li>
The following two-character sequences will be recognised as the named tokens:
<p><table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Token Name</b>
<th align=center><b>Sequence</b>
<th align=center><b>Token Name</b>
<th align=center><b>Sequence</b>
<tr valign=top><td align=left><b>ADD_ASSIGN</b>
<td align=center><b>+=</b>
<td align=left><b>NO_MATCH</b>
<td align=center><b>!~</b>
<tr valign=top><td align=left><b>SUB_ASSIGN</b>
<td align=center><b>-=</b>
<td align=left><b>EQ</b>
<td align=center><b>==</b>
<tr valign=top><td align=left><b>MUL_ASSIGN</b>
<td align=center><b>*=</b>
<td align=left><b>LE</b>
<td align=center><b>&lt;=</b>
<tr valign=top><td align=left><b>DIV_ASSIGN</b>
<td align=center><b>/=</b>
<td align=left><b>GE</b>
<td align=center><b>&gt;=</b>
<tr valign=top><td align=left><b>MOD_ASSIGN</b>
<td align=center><b>%=</b>
<td align=left><b>NE</b>
<td align=center><b>!=</b>
<tr valign=top><td align=left><b>POW_ASSIGN</b>
<td align=center><b>^=</b>
<td align=left><b>INCR</b>
<td align=center><b>++</b>
<tr valign=top><td align=left><b>OR</b>
<td align=center><b>||</b>
<td align=left><b>DECR</b>
<td align=center><b>--</b>
<tr valign=top><td align=left><b>AND</b>
<td align=center><b>&amp;&amp;</b>
<td align=left><b>APPEND</b>
<td align=center><b>&gt;&gt;</b>
</table>
<p>
<li>
The following single characters will be recognised as tokens whose
names are the character:
<pre>
<code>
&lt;newline&gt; { } ( ) [ ] , ; + - * % ^ ! &gt; &lt; | ? : ~ $ =
</code>
</pre>
<p>
</ol>
<p>
There is a lexical ambiguity between the token
<b>ERE</b>
and the tokens "/"
and
<b>DIV_ASSIGN</b>.
When an input sequence begins with a slash
character in any syntactic context where the token "/" or
<b>DIV_ASSIGN</b>
could appear as the next token in a valid program,
the longer of those two tokens that can be recognised will be recognised.
In any other syntactic context where the token
<b>ERE</b>
could appear as the next token in a valid program, the token
<b>ERE</b>
will be recognised.
</blockquote><h4><a name = "tag_000_000_109">&nbsp;</a>EXIT STATUS</h4><blockquote>
The following exit values are returned:
<dl compact>

<dt>0<dd>All input files were processed successfully.

<dt>&gt;0<dd>An error occurred.

</dl>
<p>
The exit status can be altered within the program by using an
<b>exit</b>
expression.
</blockquote><h4><a name = "tag_000_000_110">&nbsp;</a>CONSEQUENCES OF ERRORS</h4><blockquote>
If any
<i>file</i>
operand is specified and the named file
cannot be accessed,
<i>awk</i>
will write a diagnostic message to standard error
and terminate without any further action.
<p>
If the program specified by either the
<i>program</i>
operand or a
<i>progfile</i>
operand is not a valid
<i>awk</i>
program (as
specified in the EXTENDED DESCRIPTION section),
the behaviour is undefined.
<br>
</blockquote><h4><a name = "tag_000_000_111">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
The
<b>index</b>,
<b>length</b>,
<b>match</b>
and
<b>substr</b>
functions
should not be confused with similar functions in the ISO&nbsp;C standard;
the
<i>awk</i>
versions deal with characters, while the ISO&nbsp;C standard deals with bytes.
<p>
Because the concatenation operation is represented by adjacent
expressions rather than an explicit operator,
it is often necessary to use parentheses to enforce the proper
evaluation precedence.
<br>
</blockquote><h4><a name = "tag_000_000_112">&nbsp;</a>EXAMPLES</h4><blockquote>
The
<i>awk</i>
program specified in the command line
is most easily specified within single-quotes
(for example, <b>'</b><i>program</i><b>'</b>)
for applications using
<i><a href="sh.html">sh</a></i>,
because
<i>awk</i>
programs commonly contain characters that are special to the shell, including
double-quotes.
In the cases where an
<i>awk</i>
program contains single-quote characters, it is usually easiest to specify
most of the program as strings within single-quotes concatenated by the shell
with quoted single-quote characters.
For example:
<pre>
<code>
awk '/'\&quot;/ { print "quote:", $0 }'
</code>
</pre>
prints all lines from the standard input containing a single-quote character,
prefixed with
quote:.
<p>
The following are examples of simple
<i>awk</i>
programs:
<ol>
<p>
<li>
Write to the standard output all input lines
for which field 3 is greater than 5:
<pre>
<code>
$3 &gt; 5
</code>
</pre>
<p>
<li>
Write every tenth line:
<pre>
<code>
(NR % 10) == 0
</code>
</pre>
<p>
<li>
Write any line with a substring matching the regular expression:
<pre>
<code>
/(G|D)(2[0-9][[:alpha:]]*)/
</code>
</pre>
<p>
<li>
Print any line with a substring containing a G or D, followed by a
sequence of digits and characters.
This example uses character classes
<b>digit</b>
and
<b>alpha</b>
to match language-independent digit and alphabetic characters
respectively:
<pre>
<code>
/(G|D)([[:digit:][:alpha:]]*)/
</code>
</pre>
<p>
<li>
Write any line in which the second field matches the regular expression
and the fourth field does not:
<pre>
<code>
$2 ~ /xyz/ &amp;&amp; $4 ! /xyz/
</code>
</pre>
<p>
<li>
Write any line in which the second field contains a backslash:
<pre>
<code>
$2 ~ /\\/
</code>
</pre>
<p>
<li>
Write any line in which the second field contains a backslash.
Note that backslash escapes are interpreted twice, once in lexical processing
of the string and once in processing the regular expression:
<pre>
<code>
$2 ~ "\\\\"
</code>
</pre>
<p>
<li>
Write the second to the last and the
last field in each line.
Separate the fields by a colon:
<pre>
<code>
{OFS=":";print $(NF-1), $NF}
</code>
</pre>
<br>
<p>
<li>
Write the line number and number
of fields in each line.
The three strings representing the line
number, the colon and the number of
fields are concatenated and that
string is written to standard output:
<pre>
<code>
{print NR ":" NF}
</code>
</pre>
<p>
<li>
Write lines longer than 72 characters:
<pre>
<code>
length($0) &gt; 72
</code>
</pre>
<p>
<li>
Write first two fields in opposite order separated by the
<b>OFS</b>:
<pre>
<code>
{ print $2, $1 }
</code>
</pre>
<p>
<li>
Same, with input fields separated by comma or
space and tab characters, or both:
<pre>
<code>
BEGIN { FS = ",[&nbsp;\t]*|[&nbsp;\t]+" }
      { print $2, $1 }
</code>
</pre>
<p>
<li>
Add up first column, print sum and average:
<pre>
<code>
      {s += $1 }
END   {print "sum is ", s, " average is", s/NR}
</code>
</pre>
<p>
<li>
Write fields in reverse order,
one per line (many lines out for each line in):
<pre>
<code>
{ for (i = NF; i &gt; 0; --i) print $i }
</code>
</pre>
<p>
<li>
Write all lines between occurrences of
the strings
<b>start</b>
and
<b>stop</b>:
<pre>
<code>
/start/, /stop/
</code>
</pre>
<p>
<li>
Write all lines whose first field is different
from the previous one:
<pre>
<code>
$1 != prev { print; prev = $1 }
</code>
</pre>
<p>
<li>
Simulate
<i><a href="echo.html">echo</a></i>
:
<pre>
<code>
BEGIN  {
        for (i = 1; i &lt; ARGC; ++i)
        printf("%s%s", ARGV[i], i==ARGC-1?"\n":" ")
}
</code>
</pre>
<p>
<li>
Write the path prefixes contained in the
<i>PATH</i>
environment variable, one per line:
<pre>
<code>
BEGIN  {
        n = split (ENVIRON["PATH"], path, ":")
        for (i = 1; i &lt;= n; ++i)
        print path[i]
}
</code>
</pre>
<p>
<li>
If there is a file named
<b>input</b>
containing page headers of
the form:
<pre>
<dl compact><dt> <dd>
Page #
</dl>
</pre>
and a file named
<b>program</b>
that contains:
<pre>
<code>
/Page/   { $2 = n++; }
         { print }
</code>
</pre>
then the command line:
<pre>
<code>
awk -f program n=5 input
</code>
</pre>
will
print the file
<b>input</b>,
filling in page numbers starting at 5.
<p>
</ol>
</blockquote><h4><a name = "tag_000_000_113">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
The IEEE PASC 1003.2 Interpretations Committee has forwarded concerns about 
parts of this interface definition to the IEEE PASC Shell and Utilities Working Group
which is identifying the corrections.
A future revision of this specification will align with
IEEE Std. 1003.2b when finalised.
</blockquote><h4><a name = "tag_000_000_114">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="grep.html">grep</a></i>,
<i><a href="lex.html">lex</a></i>,
<i><a href="sed.html">sed</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
